<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Varargs (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="Varargs (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="Varargs (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Option-Index.html" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Target-Macros.html" rel="up" title="Target Macros">
<link href="Trampolines.html" rel="next" title="Trampolines">
<link href="Stack-and-Calling.html" rel="prev" title="Stack and Calling">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en">
<div class="section-level-extent" id="Varargs">
<div class="nav-panel">
<p>
Next: <a href="Trampolines.html" accesskey="n" rel="next">Support for Nested Functions</a>, Previous: <a href="Stack-and-Calling.html" accesskey="p" rel="prev">Stack Layout and Calling Conventions</a>, Up: <a href="Target-Macros.html" accesskey="u" rel="up">Target Description Macros and Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Implementing-the-Varargs-Macros"><span>18.10 Implementing the Varargs Macros<a class="copiable-link" href="#Implementing-the-Varargs-Macros"> &para;</a></span></h3>
<a class="index-entry-id" id="index-varargs-implementation"></a>

<p>GCC comes with an implementation of <code class="code">&lt;varargs.h&gt;</code> and
<code class="code">&lt;stdarg.h&gt;</code> that work without change on machines that pass arguments
on the stack.  Other machines require their own implementations of
varargs, and the two machine independent header files must have
conditionals to include it.
</p>
<p>ISO <code class="code">&lt;stdarg.h&gt;</code> differs from traditional <code class="code">&lt;varargs.h&gt;</code> mainly in
the calling convention for <code class="code">va_start</code>.  The traditional
implementation takes just one argument, which is the variable in which
to store the argument pointer.  The ISO implementation of
<code class="code">va_start</code> takes an additional second argument.  The user is
supposed to write the last named argument of the function here.
</p>
<p>However, <code class="code">va_start</code> should not use this argument.  The way to find
the end of the named arguments is with the built-in functions described
below.
</p>
<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_005f_005fbuiltin_005fsaveregs"><span class="category-def">Macro: </span><span><strong class="def-name">__builtin_saveregs</strong> <var class="def-var-arguments">()</var><a class="copiable-link" href="#index-_005f_005fbuiltin_005fsaveregs"> &para;</a></span></dt>
<dd><p>Use this built-in function to save the argument registers in memory so
that the varargs mechanism can access them.  Both ISO and traditional
versions of <code class="code">va_start</code> must use <code class="code">__builtin_saveregs</code>, unless
you use <code class="code">TARGET_SETUP_INCOMING_VARARGS</code> (see below) instead.
</p>
<p>On some machines, <code class="code">__builtin_saveregs</code> is open-coded under the
control of the target hook <code class="code">TARGET_EXPAND_BUILTIN_SAVEREGS</code>.  On
other machines, it calls a routine written in assembler language,
found in <samp class="file">libgcc2.c</samp>.
</p>
<p>Code generated for the call to <code class="code">__builtin_saveregs</code> appears at the
beginning of the function, as opposed to where the call to
<code class="code">__builtin_saveregs</code> is written, regardless of what the code is.
This is because the registers must be saved before the function starts
to use them for its own purposes.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_005f_005fbuiltin_005fnext_005farg"><span class="category-def">Macro: </span><span><strong class="def-name">__builtin_next_arg</strong> <var class="def-var-arguments">(<var class="var">lastarg</var>)</var><a class="copiable-link" href="#index-_005f_005fbuiltin_005fnext_005farg"> &para;</a></span></dt>
<dd><p>This builtin returns the address of the first anonymous stack
argument, as type <code class="code">void *</code>.  If <code class="code">ARGS_GROW_DOWNWARD</code>, it
returns the address of the location above the first anonymous stack
argument.  Use it in <code class="code">va_start</code> to initialize the pointer for
fetching arguments from the stack.  Also use it in <code class="code">va_start</code> to
verify that the second parameter <var class="var">lastarg</var> is the last named argument
of the current function.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-_005f_005fbuiltin_005fclassify_005ftype"><span class="category-def">Macro: </span><span><strong class="def-name">__builtin_classify_type</strong> <var class="def-var-arguments">(<var class="var">object</var>)</var><a class="copiable-link" href="#index-_005f_005fbuiltin_005fclassify_005ftype"> &para;</a></span></dt>
<dd><p>Since each machine has its own conventions for which data types are
passed in which kind of register, your implementation of <code class="code">va_arg</code>
has to embody these conventions.  The easiest way to categorize the
specified data type is to use <code class="code">__builtin_classify_type</code> together
with <code class="code">sizeof</code> and <code class="code">__alignof__</code>.
</p>
<p><code class="code">__builtin_classify_type</code> ignores the value of <var class="var">object</var>,
considering only its data type.  It returns an integer describing what
kind of type that is&mdash;integer, floating, pointer, structure, and so on.
</p>
<p>The file <samp class="file">typeclass.h</samp> defines an enumeration that you can use to
interpret the values of <code class="code">__builtin_classify_type</code>.
</p></dd></dl>

<p>These machine description macros help implement varargs:
</p>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fEXPAND_005fBUILTIN_005fSAVEREGS"><span class="category-def">Target Hook: </span><span><code class="def-type">rtx</code> <strong class="def-name">TARGET_EXPAND_BUILTIN_SAVEREGS</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fEXPAND_005fBUILTIN_005fSAVEREGS"> &para;</a></span></dt>
<dd><p>If defined, this hook produces the machine-specific code for a call to
<code class="code">__builtin_saveregs</code>.  This code will be moved to the very
beginning of the function, before any parameter access are made.  The
return value of this function should be an RTX that contains the value
to use as the return of <code class="code">__builtin_saveregs</code>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fSETUP_005fINCOMING_005fVARARGS"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_SETUP_INCOMING_VARARGS</strong> <code class="def-code-arguments">(cumulative_args_t <var class="var">args_so_far</var>, const function_arg_info <var class="var">&amp;arg</var>, int *<var class="var">pretend_args_size</var>, int <var class="var">second_time</var>)</code><a class="copiable-link" href="#index-TARGET_005fSETUP_005fINCOMING_005fVARARGS"> &para;</a></span></dt>
<dd><p>This target hook offers an alternative to using
<code class="code">__builtin_saveregs</code> and defining the hook
<code class="code">TARGET_EXPAND_BUILTIN_SAVEREGS</code>.  Use it to store the anonymous
register arguments into the stack so that all the arguments appear to
have been passed consecutively on the stack.  Once this is done, you can
use the standard implementation of varargs that works for machines that
pass all their arguments on the stack.
</p>
<p>The argument <var class="var">args_so_far</var> points to the <code class="code">CUMULATIVE_ARGS</code> data
structure, containing the values that are obtained after processing the
named arguments.  The argument <var class="var">arg</var> describes the last of these named
arguments.  The argument <var class="var">arg</var> should not be used if the function type
satisfies <code class="code">TYPE_NO_NAMED_ARGS_STDARG_P</code>, since in that case there are
no named arguments and all arguments are accessed with <code class="code">va_arg</code>.
</p>
<p>The target hook should do two things: first, push onto the stack all the
argument registers <em class="emph">not</em> used for the named arguments, and second,
store the size of the data thus pushed into the <code class="code">int</code>-valued
variable pointed to by <var class="var">pretend_args_size</var>.  The value that you
store here will serve as additional offset for setting up the stack
frame.
</p>
<p>Because you must generate code to push the anonymous arguments at
compile time without knowing their data types,
<code class="code">TARGET_SETUP_INCOMING_VARARGS</code> is only useful on machines that
have just a single category of argument register and use it uniformly
for all data types.
</p>
<p>If the argument <var class="var">second_time</var> is nonzero, it means that the
arguments of the function are being analyzed for the second time.  This
happens for an inline function, which is not actually compiled until the
end of the source file.  The hook <code class="code">TARGET_SETUP_INCOMING_VARARGS</code> should
not generate any instructions in this case.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fSTRICT_005fARGUMENT_005fNAMING"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_STRICT_ARGUMENT_NAMING</strong> <code class="def-code-arguments">(cumulative_args_t <var class="var">ca</var>)</code><a class="copiable-link" href="#index-TARGET_005fSTRICT_005fARGUMENT_005fNAMING"> &para;</a></span></dt>
<dd><p>Define this hook to return <code class="code">true</code> if the location where a function
argument is passed depends on whether or not it is a named argument.
</p>
<p>This hook controls how the <var class="var">named</var> argument to <code class="code">TARGET_FUNCTION_ARG</code>
is set for varargs and stdarg functions.  If this hook returns
<code class="code">true</code>, the <var class="var">named</var> argument is always true for named
arguments, and false for unnamed arguments.  If it returns <code class="code">false</code>,
but <code class="code">TARGET_PRETEND_OUTGOING_VARARGS_NAMED</code> returns <code class="code">true</code>,
then all arguments are treated as named.  Otherwise, all named arguments
except the last are treated as named.
</p>
<p>You need not define this hook if it always returns <code class="code">false</code>.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fCALL_005fARGS"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_CALL_ARGS</strong> <code class="def-code-arguments">(rtx, <var class="var">tree</var>)</code><a class="copiable-link" href="#index-TARGET_005fCALL_005fARGS"> &para;</a></span></dt>
<dd><p>While generating RTL for a function call, this target hook is invoked once
for each argument passed to the function, either a register returned by
<code class="code">TARGET_FUNCTION_ARG</code> or a memory location.  It is called just
before the point where argument registers are stored.  The type of the
function to be called is also passed as the second argument; it is
<code class="code">NULL_TREE</code> for libcalls.  The <code class="code">TARGET_END_CALL_ARGS</code> hook is
invoked just after the code to copy the return reg has been emitted.
This functionality can be used to perform special setup of call argument
registers if a target needs it.
For functions without arguments, the hook is called once with <code class="code">pc_rtx</code>
passed instead of an argument register.
Most ports do not need to implement anything for this hook.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fEND_005fCALL_005fARGS"><span class="category-def">Target Hook: </span><span><code class="def-type">void</code> <strong class="def-name">TARGET_END_CALL_ARGS</strong> <code class="def-code-arguments">(void)</code><a class="copiable-link" href="#index-TARGET_005fEND_005fCALL_005fARGS"> &para;</a></span></dt>
<dd><p>This target hook is invoked while generating RTL for a function call,
just after the point where the return reg is copied into a pseudo.  It
signals that all the call argument and return registers for the just
emitted call are now no longer in use.
Most ports do not need to implement anything for this hook.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fPRETEND_005fOUTGOING_005fVARARGS_005fNAMED"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_PRETEND_OUTGOING_VARARGS_NAMED</strong> <code class="def-code-arguments">(cumulative_args_t <var class="var">ca</var>)</code><a class="copiable-link" href="#index-TARGET_005fPRETEND_005fOUTGOING_005fVARARGS_005fNAMED"> &para;</a></span></dt>
<dd><p>If you need to conditionally change ABIs so that one works with
<code class="code">TARGET_SETUP_INCOMING_VARARGS</code>, but the other works like neither
<code class="code">TARGET_SETUP_INCOMING_VARARGS</code> nor <code class="code">TARGET_STRICT_ARGUMENT_NAMING</code> was
defined, then define this hook to return <code class="code">true</code> if
<code class="code">TARGET_SETUP_INCOMING_VARARGS</code> is used, <code class="code">false</code> otherwise.
Otherwise, you should not define this hook.
</p></dd></dl>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Trampolines.html">Support for Nested Functions</a>, Previous: <a href="Stack-and-Calling.html">Stack Layout and Calling Conventions</a>, Up: <a href="Target-Macros.html">Target Description Macros and Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
